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Status of This Memo 


This is an informational memo for the Internet community, and requests discussion and 
suggestions for improvements. This memo does not specify an Internet standard. 
Distribution of this memo is unlimited. 


Abstract 


This memo suggests a file format to be used to inform multiple mail reading user agent 
programs about the locally-installed facilities for handling mail in various formats. The 
mechanism is explicitly designed to work with mail systems based Internet mail as 
defined by RFC’s 821, 822, 934, 1049, 1113, and the Multipurpose Internet Mail 
Extensions, known as MIME. However, with some extensions it could probably be made 
to work for X.400-based mail systems as well. The format and mechanism are proposed 
in a manner that is generally operating-system independent. However, certain 
implementation details will inevitably reflect operating system differences, some of 
which will have to be handled in a uniform manner for each operating system. This 
memo makes such situations explicit, and, in an appendix, suggests a standard behavior 
under the UNIX operating system. 


Introduction 


The electronic mail world is in the midst of a transition from single-part text-only mail to 
multi-part, multi-media mail. In support of this transition, various extensions to RFC 821 
and RFC 822 have been proposed and/or adopted, notably including MIME [RFC-1341]. 
Various parties have demonstrated extremely high-functionality multimedia mail, but the 
problem of mail interchange between different user agents has been severe. In general, 
only text messages have been shared between user agents that were not explicitly 
designed to work together. This limitation is not compatible with a smooth transition to a 
multi-media mail world. 


One approach to this transition is to modify diverse sets of mail reading user agents so 
that, when they need to display mail of an unfamiliar (non-text) type, they consult an 
external file for information on how to display that file. That file might say, for example, 
that if the content-type of a message is "foo" it can be displayed to the user via the 
"displayfoo" program. 
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This approach means that, with a one-time modification, a wide variety of mail reading 
programs can be given the ability to display a wide variety of types of message. 
Moreover, extending the set of media types supported at a site becomes a simple matter 
of installing a binary and adding a single line to a configuration file. Crucial to this 
scheme, however, is that all of the user agents agree on a common representation and 
source for the configuration file. This memo proposes such a common representation. 


Location of Configuration Information 


Each user agent must clearly obtain the configuration information from a common 
location, if the same information is to be used to configure all user agents. However, 
individual users should be able to override or augment a site’s configuration. The 
configuration information should therefore be obtained from a designated set of 
locations. The overall configuration will be obtained through the virtual concatenation of 
several individual configuration files known as mailcap files. The configuration 
information will be obtained from the FIRST matching entry in a mailcap file, where 
"matching" depends on both a matching content-type specification, an entry containing 
sufficient information for the purposes of the application doing the searching, and the 
success of any test in the "test=" field, if present. 


The precise location of the mailcap files is operating-system dependent. A standard 
location for UNIX is specified in Appendix A. 


Overall Format of a Mailcap File 
Each mailcap file consists of a set of entries that describe the proper handling of one 
media type at the local site. For example, one line might tell how to display a message in 
Group III fax format. A mailcap file consists of a sequence of such individual entries, 
separated by newlines (according to the operating system’s newline conventions). Blank 
lines and lines that start with the "#" character (ASCII 35) are considered comments, and 
are ignored. Long entries may be continued on multiple lines if each non-terminal line 
ends with a backslash character CV, ASCII 92), in which case the multiple lines are to be 
treated as a single mailcap entry. Note that for such "continued" lines, the backslash 
must be the last character on the line to be continued. 
Thus the overall format of a mailcap file is given, in the modified BNF of RFC 822, as: 
Mailcap-File = *Mailcap-Line 
Mailcap-Line = Comment / Mailcap-Entry 


Comment = NEWLINE / "#" *CHAR NEWLINE 


NEWLINE = <newline as defined by OS convention> 
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Note that the above specification implies that comments must appear on lines all to 
themselves, with a "#" character as the first character on each comment line. 


Format of a Mailcap Entry 


Each mailcap entry consists of a number of fields, separated by semi-colons. The first 
two fields are required, and must occur in the specified order. The remaining fields are 
optional, and may appear in any order. 


The first field is the content-type, which indicates the type of data this mailcap entry 
describes how to handle. It is to be matched against the type/subtype specification in the 
"Content-Type" header field of an Internet mail message. If the subtype is specified as 
"*" it is intended to match all subtypes of the named content-type. 


The second field, view-command, is a specification of how the message or body part can 
be viewed at the local site. Although the syntax of this field is fully specified, the 
semantics of program execution are necessarily somewhat operating system dependent. 
UNIX semantics are given in Appendix A. 


The optional fields, which may be given in any order, are as follows: 


-- The "compose" field may be used to specify a program that can be used to compose a 
new body or body part in the given format. Its intended use is to support mail composing 
agents that support the composition of multiple types of mail using external composing 
agents. As with the view-command, the semantics of program execution are operating 
system dependent, with UNIX semantics specified in Appendix A. The result of the 
composing program may be data that is not yet suitable for mail transport -- that is, a 
Content-Transfer-Encoding may need to be applied to the data. 


-- The "composetyped" field is similar to the "compose" field, but is to be used when the 
composing program needs to specify the Content-type header field to be applied to the 
composed data. The "compose" field is simpler, and is preferred for use with existing 
(non-mail-oriented) programs for composing data in a given format. The 
"composetyped" field is necessary when the Content-type information must include 
auxilliary parameters, and the composition program must then know enough about mail 
formats to produce output that includes the mail type information. 


-- The "edit" field may be used to specify a program that can be used to edit a body or 
body part in the given format. In many cases, it may be identical in content to the 
"compose" field, and shares the operating-system dependent semantics for program 
execution. 


-- The "print" field may be used to specify a program that can be used to print a message 
or body part in the given format. As with the view-command, the semantics of program 
execution are operating system dependent, with UNIX semantics specified in Appendix 
A. 
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-- The "test" field may be used to test some external condition (e.g. the machine 
architecture, or the window system in use) to determine whether or not the mailcap line 
applies. It specifies a program to be run to test some condition. The semantics of 
execution and of the value returned by the test program are operating system dependent, 
with UNIX semantics specified in Appendix A. If the test fails, a subsequent mailcap 
entry should be sought. Multiple test fields are not permitted -- since a test can call a 
program, it can already be arbitrarily complex. 


-- The "needsterminal" field indicates that the view-command must be run on an 
interactive terminal. This is needed to inform window-oriented user agents that an 
interactive terminal is needed. (The decision is not left exclusively to the view-command 
because in some circumstances it may not be possible for such programs to tell whether 
or not they are on interactive terminals.) The needsterminal command should be 
assumed to apply to the compose and edit commands, too, if they exist. Note that this is 
NOT a test -- it is a requirement for the environment in which the program will be 
executed, and should typically cause the creation of a terminal window when not 
executed on either a real terminal or a terminal window. 


-- The "copiousoutput" field indicates that the output from the view-command will be an 
extended stream of output, and is to be interpreted as advice to the UA (User Agent 
mail-reading program) that the output should be either paged or made scrollable. Note 
that it is probably a mistake if needsterminal and copiousoutput are both specified. 


-- The "description" field simply provides a textual description, optionally quoted, that 
describes the type of data, to be used optionally by mail readers that wish to describe the 
data before offering to display it. 


-- The "x11-bitmap" field names a file, in X11 bitmap (xbm) format, which points to an 
appropriate icon to be used to visually denote the presence of this kind of data. 


-- Any other fields beginning with "x-" may be included for local or mailer-specific 
extensions of this format. Implementations should simply ignore all such unrecognized 
fields to permit such extensions, some of which might be standardized in a future version 
of this document. 


Some of the fields above, such as "needsterminal", apply to the actions of the view- 
command, edit-command, and compose-command, alike. In some unusual cases, this 
may not be desirable, but differentiation can be accomplished via separate mailcap 
entries, taking advantage of the fact that subsequent mailcap entries are searched if an 
earlier mailcap entry does not provide enough information: 
application/postscript; ps-to-terminal %s; \ 
needsterminal 
application/postscript; ps-to-terminal %s; \ 
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compose=idraw %s 


In RFC 822 modified BNF, the 


Mailcap-Entry 


typefield 


propertype 


implicitwild 


wildsubtype 


view-command 
mtext *mchar 
mchar schar / 


schar 


"en 
A y 


qchar w\n 


field 


namedfield 


flag = "needsterminal" 
"copiousoutput" 


/ 


/ x-token 


fieldname 


/ 
/ 
/ 
/ 
/ 
/ 
/ 
/ 


subtype / 


CHAR 


fieldname 


following grammar describes a mailcap entry: 


typefield ; view-command 
[";" 1#field] 


propertype / implicit-wild 
type "/" wildsubtype 


type 


weit 


mtext 


qchar 


* <any CHAR except 


"\", and CTLS> 


; may quote any char 


flag / namedfield 


mtext 


All these literals are to 
be interpreted as 
; cCase-insensitive 


"compose" 
"composetyped" 
"print" 

"edit " 

"test" 
"xll-bitmap" 
"description" 
x-token 


;Also all of these 
jare case-insensitive. 


Note that "type", "subtype", and "x-token" are defined in MIME. Note also that while 
the definition of "schar" includes the percent sign, "%", this character has a special 
meaning in at least the UNIX semantics, and will therefore need to be quoted as a qchar 


to be used literally. 
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Appendix A: Implementation Details for UNIX 


Although this memo fully specifies a syntax for "mailcap" files, the semantics of the 
mailcap file are of necessity operating-system dependent in four respects. In order to 
clarify the intent, and to promote a standard usage, this appendix proposes a UNIX 
semantics for these four cases. If a mailcap mechanism is implemented on non-UNIX 
systems, similar semantic decisions should be made and published. 


Location of the Mailcap File(s) 


For UNIX, a path search of mailcap files is specified. The default path search is specified 
as including at least the following: 


$HOME/.mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap 


However, this path may itself be overridden by a path specified by the MAILCAPS 
environment variable. 


Semantics of executable commands 


Several portions of a mailcap entry specify commands to be executed. In particular, the 
mandatory second field, the view-command, takes a command to be executed, as do the 
optional print, edit, test, and compose fields. 


On a UNIX system, such commands will each be a full shell command line, including the 
path name for a program and its arguments. (Because of differences in shells and the 
implementation and behavior of the same shell from one system to another, it is specified 
that the command line be intended as input to the Bourne shell, i.e. that it is implicitly 
preceded by "/bin/sh -c " on the command line.) 


The two characters "%s", if used, will be replaced by the name of a file for the actual 
mail body data. In the case of the edit adn view-command, the body part will be passed 
to this command as standard input unless one or more instances of "%s" appear in the 
view-command, in which case %s will be replaced by the name of a file containing the 
body part, a file which may have to be created before the view-command program is 
executed. (Such files cannot be presumed to continue to exist after the view-command 
program exits. Thus a view-command that wishes to exit and continue processing in the 
background should take care to save the data first.) In the case of the compose and 
composetyped commands, %s should be replaced by the name of a file to which the 
composed data should be written by the programs named in the compose or 
composedtyped commands. Thus, the calling program will look in that file later in order 
to retrieve the composed data. If %s does not appear in the compose or composetyped 
commands, then the composed data will be assumed to be written by the composing 
programs to standard output. 
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Furthermore, any occurrence of "%t" will be replaced by the content-type and subtype 
specification. (That is, if the content-type is "text/plain", then %t will be replaced by 
"text/plain".) A literal % character may be quoted as \%. Finally, named parameters 
from the Content-type field may be placed in the command execution line using "%{" 
followed by the parameter name and a closing "}" character. The entire parameter 
should appear as a single command line argument, regardless of embedded spaces. Thus, 
if the message has a Content-type line of: 


Content-type: multipart/mixed; boundary=42 
and the mailcap file has a line of: 


multipart/*; /usr/local/bin/showmulti \ 
St S{boundary } 


then the equivalent of the following command should be executed: 
/usr/local/bin/showmulti multipart/mixed 42 
Semantics of the "test" field 


The "test" field specifies a program to be used to test whether or not the current mailcap 
line applies. This can be used, for example, to have a mailcap line that only applies if the 
X window system is running, or if the user is running on a SPARCstation with a 
/dev/audio. The value of the "test" field is a program to run to test such a condition. The 
precise program to run and arguments to give it are determined as specified in the 
previous section. The test program should return an exit code of zero if the condition is 
true, and a non-zero code otherwise. 


Semantics of the "compose" field 

On UNIX, the composing program is expected to produce a data stream for such a body 
part as its standard output. The program will be executed with the command line 
arguments determined as specified above. The data returned via its standard output will 
be given a Content-Type field that has no supplementary parameters. For example, the 


following mailcap entry: 


audio/basic; /usr/local/bin/showaudio %t 
compose = /usr/local/bin/recordaudio 


would result in tagging the data composed by the "recordaudio" program as: 
Content-Type: audio/basic 
If this is unacceptable -- for example, in the case of multipart mail a "boundary" 


parameter is required -- then the "compose" field cannot be used. Instead, the 
"composetyped" field should be used in the mailcap file. 
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Semantics of the ''composetyped" field 


The "composetyped" filed is much like the "compose" field, except that it names a 
composition program that produces, not raw data, but data that includes a MIME- 
conformant type specification. The program will be executed with the command line 
arguments determined as specified above. The data returned via its standard output must 
begin with a Content-Type header, followed optionally by other Content-* headers, and 
then by a blank line and the data. For example, the following mailcap entry: 


multipart/mixed; /usr/local/bin/showmulti %t \ 
S{boundary}; \ 
composetyped = /usr/local/bin/makemulti 


would result in executing the "makemulti" program, which would be expected to begin 
its output with a line of the form: 


Content-Type: multipart/mixed; boundary=foobar 


Note that a composition program need not encode binary data in base64 or quoted- 
printable. It remains the responsibility of the software calling the composition program to 
encode such data as necessary. However, if a composing program does encode data, 
which is not encouraged, it should announce that fact using a Content-Transfer-Encoding 
header in the standard manner defined by MIME. Because such encodings must be 
announced by such a header, they are an option only for composetyped programs, not for 
compose programs. 


Appendix B: Sample Mailcap File 


The following is an example of a mailcap file for UNIX that demonstrates most of the 
syntax above. It contains explanatory comments where necessary. 


# Mailcap file for Bellcore lab 214. 

# 

# The next line sends "richtext" to the richtext program 

text/richtext; richtext %s; copiousoutput 

# 

# Next, basic u-law audio 

audio/*; showaudio; test=/usr/local/bin/hasaudio 

# 

# Next, use the xview program to handle several image formats 

image/*; xview %s; test=/usr/local/bin/RunningX 

# 

# The ATOMICMAIL interpreter uses curses, so needs a terminal 

application/atomicmail; /usr/local/bin/atomicmail %s; \ 
needsterminal 


# 
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# The next line handles Andrew format, 
# if ez and ezview are installed 
x-be2; /usr/andrew/bin/ezview %s; 
print=/usr/andrew/bin/ezprint % 
compose=/usr/andrew/bin/ez -d % 
edit=/usr/andrew/bin/ez -d %s; 
copiousoutput 
# 
# The next silly example demonstrates the use of quoting 
application/*; echo "This is \\"%St\\" but \ 
is 50 \% Greek to me" \; cat %s; copiousoutput 


Appendix C: A Note on Format Translation 


It has been suggested that another function of a mailcap-like mechanism might be to 
specify the locally available tools for document format translation. For example, the file 
could designate a program for translating from format A to format B, another for 
translating from format B to format C, and finally a mechanism for displaying format C. 
Although this mechanism would be somewhat richer than the current mailcap file, and 
might conceivably also have utility at the message transport layer, it significantly 
complicates the processing effort necessary for a user agent that simply wants to display 
a message in format A. Using the current, simpler, mailcap scheme, a single line could 
tell such a user agent to display A-format mail using a pipeline of translators and the C- 
format viewer. This memo resists the temptation to complicate the necessary processing 
for a user agent to accomplish this task. Using the mailcap format defined here, it is only 
necessary to find the correct single line in a mailcap file, and to execute the command 
given in that line. 
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Security Considerations 


Security issues are not discussed in this memo. However, the use of the mechanisms 
described in this memo can make it easier for implementations to slip into the kind of 
security problems discussed in the MIME document. Implementors and mailcap 
administrators should be aware of these security considerations, and in particular should 
exercise caution in the choice of programs to be listed in a mailcap file for automatic 
execution. 
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